Sets the background color or pattern for user panes that support embedding.

typedef void(* ControlUserPaneBackgroundProcPtr) (
    ControlRef control, 
    ControlBackgroundPtr info
);

You would declare your function like this if you were to name it MyControlUserPaneBackgroundCallback:

void MyControlUserPaneBackgroundCallback (
    ControlRef control, 
    ControlBackgroundPtr info
);

control

A handle to the control for which the background color or pattern is to be set.

info

A pointer to information such as the depth and type of the drawing device.

DISCUSSION

The Control Manager defines the data type ControlUserPaneBackgroundUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr ControlUserPaneBackgroundUPP;

You typically use the NewControlUserPaneBackgroundProc macro like this:

ControlUserPaneBackgroundUPP myControlUserPaneBackgroundUPP;

myControlUserPaneBackgroundUPP = NewControlUserPaneBackgroundProc (MyControlUserPaneBackgroundCallback);

You typically use the CallControlUserPaneBackgroundProc macro like this:

CallControlUserPaneBackgroundProc(myControlUserPaneBackgroundUPP, control, info);

Your MyControlUserPaneBackgroundCallback function should set the user pane background color or pattern to whatever is appropriate given the bit depth and device type passed in. Your MyControlUserPaneBackgroundCallback function is called to set up the background color. This ensures that when an embedded control calls EraseRgn or EraseRect, the background is erased to the correct color or pattern.

This function is called only if there is a control embedded in the user pane and if you’ve set the kControlHasSpecialBackground and kControlSupportsEmbedding feature bits on creation of the user pane control.

Once you have provided a user pane application-defined function, you can call the function SetControlData in order to associate your function with a control. User pane application-defined functions are identified to SetControlData by tag constants; for a description of the tag constants, see the “Control Manager Constants” section. For example, once you have created the function MyControlUserPaneBackgroundCallback, pass kControlUserPaneBackgroundProcTag in the tagName parameter of SetControlData.

VERSION NOTES

This function is available with Appearance Manager 1.0 and later.

AVAILABILITY

Supported in Carbon.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)